package com.southminority.ethnic.service.heritage;

import com.southminority.ethnic.common.result.PageResult;
import com.southminority.ethnic.controller.heritage.vo.HeritageVO;
import com.southminority.ethnic.pojo.Heritage;
import com.southminority.ethnic.pojo.Inheritor;

import java.util.List;

/**
 * 非物质文化遗产项目服务接口.
 * <p>
 * 定义了非遗模块的核心业务逻辑，包括前端展示和后台管理的所有功能。
 * 
 * @author SouthMinority
 */
public interface HeritageService {

    // =================================================================================
    // ==                             前端展示相关方法 (Public API)                     ==
    // =================================================================================

    /**
     * 获取所有已发布的非遗项目列表（用于前端首页或列表页展示）.
     *
     * @return {@link List<HeritageVO>} 非遗项目视图对象列表.
     */
    List<HeritageVO> getHeritageList();

    /**
     * 根据多个筛选条件查询已发布的非遗项目列表.
     *
     * @param heritageType 非遗类型 (可选).
     * @param level        级别 (可选).
     * @param region       地区 (可选).
     * @param ethnicGroup  民族 (可选).
     * @param keyword      搜索关键词 (可选, 模糊匹配名称、描述等).
     * @param sortBy       排序字段 (可选, 如 'view_count', 'approval_date').
     * @param sortOrder    排序顺序 (可选, 'asc' 或 'desc').
     * @return {@link List<HeritageVO>} 符合条件的非遗项目列表.
     */
    List<HeritageVO> getHeritageListByCondition(String heritageType, String level, 
                                              String region, String ethnicGroup, 
                                              String keyword, String sortBy, String sortOrder);

    /**
     * 根据ID获取单个非遗项目的详细信息（用于前端详情页）.
     * <p>
     * 此方法会增加项目的浏览次数, 并会一并查询该项目下的传承人和相关研究成果。
     *
     * @param id 非遗项目的唯一标识ID.
     * @return {@link HeritageVO} 包含完整信息的非遗项目视图对象.
     */
    HeritageVO getHeritageDetail(Long id);

    /**
     * 为指定的非遗项目增加一次浏览次数.
     *
     * @param id 非遗项目的唯一标识ID.
     * @return {@link Integer} 更新后的总浏览次数.
     */
    Integer increaseViewCount(Long id);

    /**
     * 获取系统中所有不重复的非遗类型列表（用于前端筛选菜单）.
     *
     * @return {@link List<String>} 非遗类型字符串列表.
     */
    List<String> getHeritageTypes();

    /**
     * 获取系统中所有不重复的项目级别列表（用于前端筛选菜单）.
     *
     * @return {@link List<String>} 级别字符串列表.
     */
    List<String> getLevels();

    /**
     * 获取系统中所有不重复的地区列表（用于前端筛选菜单）.
     *
     * @return {@link List<String>} 地区字符串列表.
     */
    List<String> getRegions();

    /**
     * 获取系统中所有不重复的民族列表（用于前端筛选菜单）.
     *
     * @return {@link List<String>} 民族字符串列表.
     */
    List<String> getEthnicGroups();

    // =================================================================================
    // ==                             后台管理相关方法 (Admin API)                      ==
    // =================================================================================

    /**
     * 分页查询非遗项目（用于后台管理列表）.
     *
     * @param page         当前页码.
     * @param size         每页显示数量.
     * @param keyword      搜索关键词 (可选).
     * @param heritageType 非遗类型 (可选).
     * @param level        级别 (可选).
     * @param status       状态 (可选, 1-已发布, 0-草稿, -1-已删除).
     * @return {@link PageResult<HeritageVO>} 封装了分页信息的查询结果.
     */
    PageResult<HeritageVO> getHeritagePageForAdmin(Integer page, Integer size,
                                                 String keyword, String heritageType,
                                                 String level, Integer status);

    /**
     * 创建一个新的非遗项目.
     *
     * @param heritage 包含非遗项目所有信息的POJO对象.
     * @return {@link HeritageVO} 创建成功后返回的非遗项目视图对象.
     */
    HeritageVO createHeritage(Heritage heritage);

    /**
     * 更新一个已存在的非遗项目.
     *
     * @param id       要更新的非遗项目的ID.
     * @param heritage 包含更新后信息的POJO对象.
     * @return {@link HeritageVO} 更新成功后返回的非遗项目视图对象.
     */
    HeritageVO updateHeritage(Long id, Heritage heritage);

    /**
     * 根据ID删除一个非遗项目（逻辑删除）.
     *
     * @param id 要删除的非遗项目的ID.
     * @return 操作成功返回true, 否则返回false.
     */
    Boolean deleteHeritage(Long id);

    /**
     * 批量删除非遗项目（逻辑删除）.
     *
     * @param ids 包含多个要删除的非遗项目ID的列表.
     * @return 操作成功返回true, 否则返回false.
     */
    Boolean batchDeleteHeritage(List<Long> ids);

    /**
     * 更新指定非遗项目的状态.
     *
     * @param id     非遗项目的ID.
     * @param status 新的状态值 (例如: 1-已发布, 0-草稿).
     * @return 操作成功返回true, 否则返回false.
     */
    Boolean updateHeritageStatus(Long id, Integer status);

    /**
     * 获取非遗项目详情（用于后台管理编辑页）.
     *
     * @param id 非遗项目的ID.
     * @return {@link HeritageVO} 包含完整信息的非遗项目视图对象.
     */
    HeritageVO getHeritageDetailForAdmin(Long id);

    /**
     * 为某个非遗项目创建一个新的传承人.
     *
     * @param inheritor 包含传承人信息的POJO对象.
     * @return 操作成功返回true, 否则返回false.
     */
    Boolean createInheritor(Inheritor inheritor);

    /**
     * 更新一个已存在的传承人信息.
     *
     * @param id        要更新的传承人的ID.
     * @param inheritor 包含更新后信息的POJO对象.
     * @return 操作成功返回true, 否则返回false.
     */
    Boolean updateInheritor(Long id, Inheritor inheritor);

    /**
     * 根据ID删除一个传承人（逻辑删除）.
     *
     * @param id 要删除的传承人的ID.
     * @return 操作成功返回true, 否则返回false.
     */
    Boolean deleteInheritor(Long id);

    /**
     * 根据非遗项目ID获取其下所有的传承人列表.
     *
     * @param heritageId 非遗项目的ID.
     * @return {@link List<Inheritor>} 传承人实体对象列表.
     */
    List<Inheritor> getInheritorsByHeritageId(Long heritageId);

    /**
     * 分页查询传承人（后台管理）。
     *
     * @param page        当前页码
     * @param size        每页大小
     * @param heritageId  可选：所属非遗项目ID
     * @param keyword     可选：按姓名/民族/级别/专长模糊查询
     * @param status      可选：状态过滤，默认排除已删除（-1）
     * @return PageResult<Inheritor>
     */
    PageResult<Inheritor> getInheritorPageForAdmin(Integer page, Integer size,
                                                   Long heritageId, String keyword, Integer status);
}
